<html>
    <head>
        <title>Simian - Similarity Analyser | Duplicate Code Detection for the Enterprise | Installation</title>
    </head>

    <body>
        <h3>Installation</h3>
        <p>To install, simply unzip the contents of the distribution zip file into a directory and choose one of the
        various methods for running Simian:
        <ul>
            <li><a href="#cli">Command line interface</a></li>
            <li><a href="#ant">Ant task</a></li>
            <li><a href="#checkstyle">Checkstyle plugin</a></li>
            <li><a href="#intelliJ">IntelliJ integration</a></li>
            <li><a href="javadoc/index.html">Programmatic Interface</a></li>
            <li><a href="http://www.maven.org" target="_blank">Maven</a></li>
            <li><a href="http://www.integility.com/simian_ui" target="_blank">Eclipse plugin</a></li>
        </ul></p>

        <a name="cli"/>
        <h3>Command Line Interface</h3>
        <p>This method allows you to execute Simian from the command line, shell scripts, batch files, etc. scanning a
        directory for all files matching a pattern.</p>

        <p>The general form for the <a href="http://www.java.com" target="_blank">Java</a> version is:
        <pre>
    java -jar simian.jar [options] [files]</pre></p>

        <p>And for the <a href="http://www.microsoft.com/net">.NET</a> version is:
        <pre>
    simian.exe [options] [files]</pre></p>

        <p>The <code>files</code> can be specified as any regular shell glob or simply a list of files and can be mixed
            with the <code>-includes</code> option. (See below for examples.)</p>

        <p>For example, to find all java files in all sub-directories of the current directory:
        <pre>    &quot;**/*.java&quot;</pre></p>

        <p>To find all java files in the current directory and set the threshold to 3:
        <pre>    -threshold=3 &quot;*.java&quot;</pre></p>

        <p>To find all C# files in the current directory:
        <pre>    &quot;*.cs&quot;</pre></p>

        <p>To find all C and header in all sub-directories of the current directory:
        <pre>    **/*.c **/*.h</pre></p>

        <p>To find all java files in two different directories:
        <pre>    &quot;/csharp-source/*.cs&quot; &quot;/java-source/*.java&quot;</pre></p>

        <p>To find all java files in all sub-directories, excluding Test classes:
        <pre>    -includes=**/*.java -excludes=**/*Test.java</pre></p>

        <p>To find all java files in the current directory and ignore numbers:
        <pre>    -ignoreNumbers &quot;*.java&quot;</pre></p>

        <p>To find all java files and display the results in xml format:
        <pre>    -formatter=xml &quot;*.rb&quot;</pre></p>

        <p>To find all ruby files and sends the results in emacs compatible format to a file:
        <pre>    -formatter=emacs:c:\temp\simian.log &quot;*.rb&quot;</pre></p>

        <p>To read configuration from a file (where each line of the file specifies at most one of any of the valid
        command-line arguments):
        <pre>    -config=simian.config</pre></p>

        <h3>Notes</h3>
        <p>For most projects (including the nearly 400,000 LOC JDK 1.4 source base), the default VM size seems to be
        adequate. If you encounter:
        <pre>    Exception in thread "main" java.lang.OutOfMemoryError</pre></p>

        <p>you will need to increase the VM heap size using the <code>-mx</code> JVM option.</p>

        <a name="ant"/>
        <h3>Ant Task</h3>
        <p>This method allows you to integrate Simian with the <a href="http://ant.apache.org" target="_blank">Ant</a>,
        a java based build tool.</p>

        <p>Somewhere in your build.xml file, define the task:
        <pre>    &lt;taskdef resource="simiantask.properties" classpath="simian.jar"/&gt;</pre></p>

        <p>And finally, create a target to run the checker. For all defaults:
        <pre>    &lt;simian&gt;
        &lt;fileset dir="./main" includes="**/*.java"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>To exclude test classes if they exists in the same tree as the source:
        <pre>    &lt;simian threshold="6"&gt;
        &lt;fileset dir="./main" includes="**/*.java" excludes="**/*Test.java"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>To change the minimum number of lines that is considered a match:
        <pre>    &lt;simian threshold="6"&gt;
        &lt;fileset dir="./main" includes="**/*.java"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>To force the language used for processing:
        <pre>    &lt;simian language="java"&gt;
        &lt;fileset dir="./main" includes="**/*.*"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>To have the build fail one or more matches are found:
        <pre>    &lt;simian failOnDuplication="true"&gt;
        &lt;fileset dir="./main" includes="**/*.java"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>To set a build property if one or more matches are found:
        <pre>    &lt;simian failureProperty="test.failure"&gt;
        &lt;fileset dir="./main" includes="**/*.java"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>By default, Simian outputs plain text using the default Ant logger. You can override this by using the nested
        <code>formatter</code> element. The <code>formatter</code> takes a <code>type</code> (either <code>"plain"</code>;
        <code>"xml"</code>; <code>"emacs"</code>; <code>"vs"</code>; or <code>"yml"</code>) and an optional filename
        (<code>toFile</code>). For example, to send output to a file:
        <pre>    &lt;simian&gt;
        &lt;formatter type="plain" toFile="simian-log.txt"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>To produce XML output:
        <pre>    &lt;simian&gt;
        &lt;formatter type="xml" toFile="simian-log.xml"/&gt;
    &lt;/simian&gt;</pre></p>

        <p>You may specify any number of formatter elements allowing you to produce both XML and plain text output if
        necessary</p>

        <a name="checkstyle"/>
        <h3>Checkstyle Plugin</h3>
        <p>This method allows you to integrate Simian with
        <a href="http://checkstyle.sourceforge.net" target="_blank">Checkstyle 3+</a>. A remarkable java based code
        checker.</p>

        <p>First, ensure the simian.jar file is on the classpath. Next, add the check to your configuiration file.
        (Note: The plugin runs as a FileSetCheck):
        <pre>    &lt;module name="Checker"&gt;
        ...

        &lt;module name="com.harukizaemon.simian.SimianCheck"/&gt;
    &lt;/module&gt;</pre></p>

        <p>To change the minimum number of lines that is considered a match:
        <pre>    &lt;module name="com.harukizaemon.simian.SimianCheck"/&gt;
        &lt;property name="threshold" value="6"/&gt;
    &lt;module/&gt;</pre></p>

        <p>To force the language used for processing:
        <pre>    &lt;module name="com.harukizaemon.simian.SimianCheck"/&gt;
        &lt;property name="language" value="java"/&gt;
    &lt;module/&gt;</pre></p>

        <a name="intellij"/>
        <h3>IntelliJ Integration</h3>
        <p>This method allows you to integrate Simian with
        <a href="http://www.intellij.com" target="_blank">IntelliJ</a> as an external tool. This will then allow you to
        run simian from within IntelliJ and go straight to any matches by clicking on the file location.</p>

        <p>This is really a short-cut way to define the tool using <code>Options|External Tools</code>.</p>

        <p>Open the <code>_.xml</code> file in the <code>config/tools</code> directory of the your intellij settings (usually
        under the intellij home directory or under your home directory as <code>.IntelliJIdea</code>).</p>

        <p>Add the following block:
        <pre>    &lt;tool name="Simian" showInMainMenu="true" showInEditor="true" showInProject="true"
          showInSearchPopup="true" disabled="false" useConsole="true" synchronizeAfterRun="true"&gt;
    &lt;exec&gt;
      &lt;option name="COMMAND" value="$JDKPath$\bin\java.exe" /&gt;
      &lt;option name="PARAMETERS" value="-jar simian.jar $FileDir$\**\*.java" /&gt;
      &lt;option name="WORKING_DIRECTORY" /&gt;
    &lt;/exec&gt;
    &lt;filter&gt;
      &lt;option name="NAME" value="Duplicate Location" /&gt;
      &lt;option name="DESCRIPTION" value="" /&gt;
      &lt;option name="REGEXP" value=" Between lines $LINE$ and [0-9]* in $FILE_PATH$" /&gt;
    &lt;/filter&gt;
  &lt;/tool&gt;</pre></p>

        <p>Make sure to put the full path to simian.jar in the <code>PARAMETERS</code> option and the appropriate java
        runtime in the <code>COMMAND</code> option.</p>

        <p>The <code>PARAMETERS</code> follows the general form of the <a href="#cli">command line interface</a> allowing
        you to set parsing options, threshold, etc.</p>

        <p>Re-start IntelliJ and you can click on <code>Tools|Simian</code>.</p>

        <p>You should be able to click on the matching lines and go straight to the source code.</p>

        <hr />
        <p align="center"><font size=".5">Java and all Java-based marks are trademarks or registered trademarks of Sun
        Microsystems, Inc. in the United States and other countries.<br /><br />

        .NET and all .NET-based marks are trademarks or registered trademarks of Microsoft&reg; in the United States and
        other countries.<br /><br />

        Copyright (c) 2003-11 Simon Harris.  All rights reserved.</font></p>
    </body>
</html>
